<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>28.2. ensurepip — Bootstrapping the pip installer &mdash; Python 3.4.3 documentation</title>
    
    <link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../',
        VERSION:     '3.4.3',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <script type="text/javascript" src="../_static/sidebar.js"></script>
    <link rel="search" type="application/opensearchdescription+xml"
          title="Search within Python 3.4.3 documentation"
          href="../_static/opensearch.xml"/>
    <link rel="author" title="About these documents" href="../about.html" />
    <link rel="copyright" title="Copyright" href="../copyright.html" />
    <link rel="top" title="Python 3.4.3 documentation" href="../index.html" />
    <link rel="up" title="28. Software Packaging and Distribution" href="distribution.html" />
    <link rel="next" title="28.3. venv — Creation of virtual environments" href="venv.html" />
    <link rel="prev" title="28.1. distutils — Building and installing Python modules" href="distutils.html" />
    <link rel="shortcut icon" type="image/png" href="../_static/py.png" />
    <script type="text/javascript" src="../_static/copybutton.js"></script>
    <script type="text/javascript" src="../_static/version_switch.js"></script>
    
 

  </head>
  <body>  
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="../py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="venv.html" title="28.3. venv — Creation of virtual environments"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="distutils.html" title="28.1. distutils — Building and installing Python modules"
             accesskey="P">previous</a> |</li>
        <li><img src="../_static/py.png" alt=""
                 style="vertical-align: middle; margin-top: -1px"/></li>
        <li><a href="https://www.python.org/">Python</a> &raquo;</li>
        <li>
          <span class="version_switcher_placeholder">3.4.3</span>
          <a href="../index.html">Documentation</a> &raquo;
        </li>

          <li><a href="index.html" >The Python Standard Library</a> &raquo;</li>
          <li><a href="distribution.html" accesskey="U">28. Software Packaging and Distribution</a> &raquo;</li> 
      </ul>
    </div>    

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="module-ensurepip">
<span id="ensurepip-bootstrapping-the-pip-installer"></span><h1>28.2. <a class="reference internal" href="#module-ensurepip" title="ensurepip: Bootstrapping the &quot;pip&quot; installer into an existing Python installation or virtual environment."><tt class="xref py py-mod docutils literal"><span class="pre">ensurepip</span></tt></a> &#8212; Bootstrapping the <tt class="docutils literal"><span class="pre">pip</span></tt> installer<a class="headerlink" href="#module-ensurepip" title="Permalink to this headline">¶</a></h1>
<div class="versionadded">
<p><span class="versionmodified">New in version 3.4.</span></p>
</div>
<p>The <a class="reference internal" href="#module-ensurepip" title="ensurepip: Bootstrapping the &quot;pip&quot; installer into an existing Python installation or virtual environment."><tt class="xref py py-mod docutils literal"><span class="pre">ensurepip</span></tt></a> package provides support for bootstrapping the <tt class="docutils literal"><span class="pre">pip</span></tt>
installer into an existing Python installation or virtual environment. This
bootstrapping approach reflects the fact that <tt class="docutils literal"><span class="pre">pip</span></tt> is an independent
project with its own release cycle, and the latest available stable version
is bundled with maintenance and feature releases of the CPython reference
interpreter.</p>
<p>In most cases, end users of Python shouldn&#8217;t need to invoke this module
directly (as <tt class="docutils literal"><span class="pre">pip</span></tt> should be bootstrapped by default), but it may be
needed if installing <tt class="docutils literal"><span class="pre">pip</span></tt> was skipped when installing Python (or
when creating a virtual environment) or after explicitly uninstalling
<tt class="docutils literal"><span class="pre">pip</span></tt>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This module <em>does not</em> access the internet. All of the components
needed to bootstrap <tt class="docutils literal"><span class="pre">pip</span></tt> are included as internal parts of the
package.</p>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<dl class="last docutils">
<dt><a class="reference internal" href="../installing/index.html#installing-index"><em>Installing Python Modules</em></a></dt>
<dd>The end user guide for installing Python packages</dd>
<dt><span class="target" id="index-0"></span><a class="pep reference external" href="http://www.python.org/dev/peps/pep-0453"><strong>PEP 453</strong></a>: Explicit bootstrapping of pip in Python installations</dt>
<dd>The original rationale and specification for this module.</dd>
</dl>
</div>
<div class="section" id="command-line-interface">
<h2>28.2.1. Command line interface<a class="headerlink" href="#command-line-interface" title="Permalink to this headline">¶</a></h2>
<p>The command line interface is invoked using the interpreter&#8217;s <tt class="docutils literal"><span class="pre">-m</span></tt> switch.</p>
<p>The simplest possible invocation is:</p>
<div class="highlight-python3"><div class="highlight"><pre><span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">ensurepip</span>
</pre></div>
</div>
<p>This invocation will install <tt class="docutils literal"><span class="pre">pip</span></tt> if it is not already installed,
but otherwise does nothing. To ensure the installed version of <tt class="docutils literal"><span class="pre">pip</span></tt>
is at least as recent as the one bundled with <tt class="docutils literal"><span class="pre">ensurepip</span></tt>, pass the
<tt class="docutils literal"><span class="pre">--upgrade</span></tt> option:</p>
<div class="highlight-python3"><div class="highlight"><pre><span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">ensurepip</span> <span class="o">--</span><span class="n">upgrade</span>
</pre></div>
</div>
<p>By default, <tt class="docutils literal"><span class="pre">pip</span></tt> is installed into the current virtual environment
(if one is active) or into the system site packages (if there is no
active virtual environment). The installation location can be controlled
through two additional command line options:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">--root</span> <span class="pre">&lt;dir&gt;</span></tt>: Installs <tt class="docutils literal"><span class="pre">pip</span></tt> relative to the given root directory
rather than the root of the currently active virtual environment (if any)
or the default root for the current Python installation.</li>
<li><tt class="docutils literal"><span class="pre">--user</span></tt>: Installs <tt class="docutils literal"><span class="pre">pip</span></tt> into the user site packages directory rather
than globally for the current Python installation (this option is not
permitted inside an active virtual environment).</li>
</ul>
<p>By default, the scripts <tt class="docutils literal"><span class="pre">pipX</span></tt> and <tt class="docutils literal"><span class="pre">pipX.Y</span></tt> will be installed (where
X.Y stands for the version of Python used to invoke <tt class="docutils literal"><span class="pre">ensurepip</span></tt>). The
scripts installed can be controlled through two additional command line
options:</p>
<ul>
<li><p class="first"><tt class="docutils literal"><span class="pre">--altinstall</span></tt>: if an alternate installation is requested, the <tt class="docutils literal"><span class="pre">pipX</span></tt>
script will <em>not</em> be installed.</p>
</li>
<li><dl class="first docutils">
<dt><tt class="docutils literal"><span class="pre">--default-pip</span></tt>: if a &#8220;default pip&#8221; installation is requested, the</dt>
<dd><p class="first last"><tt class="docutils literal"><span class="pre">pip</span></tt> script will be installed in addition to the two regular scripts.</p>
</dd>
</dl>
</li>
</ul>
<p>Providing both of the script selection options will trigger an exception.</p>
</div>
<div class="section" id="module-api">
<h2>28.2.2. Module API<a class="headerlink" href="#module-api" title="Permalink to this headline">¶</a></h2>
<p><a class="reference internal" href="#module-ensurepip" title="ensurepip: Bootstrapping the &quot;pip&quot; installer into an existing Python installation or virtual environment."><tt class="xref py py-mod docutils literal"><span class="pre">ensurepip</span></tt></a> exposes two functions for programmatic use:</p>
<dl class="function">
<dt id="ensurepip.version">
<tt class="descclassname">ensurepip.</tt><tt class="descname">version</tt><big>(</big><big>)</big><a class="headerlink" href="#ensurepip.version" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a string specifying the bundled version of pip that will be
installed when bootstrapping an environment.</p>
</dd></dl>

<dl class="function">
<dt id="ensurepip.bootstrap">
<tt class="descclassname">ensurepip.</tt><tt class="descname">bootstrap</tt><big>(</big><em>root=None</em>, <em>upgrade=False</em>, <em>user=False</em>, <em>altinstall=False</em>, <em>default_pip=False</em>, <em>verbosity=0</em><big>)</big><a class="headerlink" href="#ensurepip.bootstrap" title="Permalink to this definition">¶</a></dt>
<dd><p>Bootstraps <tt class="docutils literal"><span class="pre">pip</span></tt> into the current or designated environment.</p>
<p><em>root</em> specifies an alternative root directory to install relative to.
If <em>root</em> is None, then installation uses the default install location
for the current environment.</p>
<p><em>upgrade</em> indicates whether or not to upgrade an existing installation
of an earlier version of <tt class="docutils literal"><span class="pre">pip</span></tt> to the bundled version.</p>
<p><em>user</em> indicates whether to use the user scheme rather than installing
globally.</p>
<p>By default, the scripts <tt class="docutils literal"><span class="pre">pipX</span></tt> and <tt class="docutils literal"><span class="pre">pipX.Y</span></tt> will be installed (where
X.Y stands for the current version of Python).</p>
<p>If <em>altinstall</em> is set, then <tt class="docutils literal"><span class="pre">pipX</span></tt> will <em>not</em> be installed.</p>
<p>If <em>default_pip</em> is set, then <tt class="docutils literal"><span class="pre">pip</span></tt> will be installed in addition to
the two regular scripts.</p>
<p>Setting both <em>altinstall</em> and <em>default_pip</em> will trigger
<a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><tt class="xref py py-exc docutils literal"><span class="pre">ValueError</span></tt></a>.</p>
<p><em>verbosity</em> controls the level of output to <a class="reference internal" href="sys.html#sys.stdout" title="sys.stdout"><tt class="xref py py-data docutils literal"><span class="pre">sys.stdout</span></tt></a> from the
bootstrapping operation.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The bootstrapping process has side effects on both <tt class="docutils literal"><span class="pre">sys.path</span></tt> and
<tt class="docutils literal"><span class="pre">os.environ</span></tt>. Invoking the command line interface in a subprocess
instead allows these side effects to be avoided.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The bootstrapping process may install additional modules required by
<tt class="docutils literal"><span class="pre">pip</span></tt>, but other software should not assume those dependencies will
always be present by default (as the dependencies may be removed in a
future version of <tt class="docutils literal"><span class="pre">pip</span></tt>).</p>
</div>
</dd></dl>

</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
  <h3><a href="../contents.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">28.2. <tt class="docutils literal"><span class="pre">ensurepip</span></tt> &#8212; Bootstrapping the <tt class="docutils literal"><span class="pre">pip</span></tt> installer</a><ul>
<li><a class="reference internal" href="#command-line-interface">28.2.1. Command line interface</a></li>
<li><a class="reference internal" href="#module-api">28.2.2. Module API</a></li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="distutils.html"
                        title="previous chapter">28.1. <tt class="docutils literal"><span class="pre">distutils</span></tt> &#8212; Building and installing Python modules</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="venv.html"
                        title="next chapter">28.3. <tt class="docutils literal"><span class="pre">venv</span></tt> &#8212; Creation of virtual environments</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
  <li><a href="../bugs.html">Report a Bug</a></li>
  <li><a href="../_sources/library/ensurepip.txt"
         rel="nofollow">Show Source</a></li>
</ul>

<div id="searchbox" style="display: none">
  <h3>Quick search</h3>
    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    <p class="searchtip" style="font-size: 90%">
    Enter search terms or a module, class or function name.
    </p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>  
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="../py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="venv.html" title="28.3. venv — Creation of virtual environments"
             >next</a> |</li>
        <li class="right" >
          <a href="distutils.html" title="28.1. distutils — Building and installing Python modules"
             >previous</a> |</li>
        <li><img src="../_static/py.png" alt=""
                 style="vertical-align: middle; margin-top: -1px"/></li>
        <li><a href="https://www.python.org/">Python</a> &raquo;</li>
        <li>
          <span class="version_switcher_placeholder">3.4.3</span>
          <a href="../index.html">Documentation</a> &raquo;
        </li>

          <li><a href="index.html" >The Python Standard Library</a> &raquo;</li>
          <li><a href="distribution.html" >28. Software Packaging and Distribution</a> &raquo;</li> 
      </ul>
    </div>  
    <div class="footer">
    &copy; <a href="../copyright.html">Copyright</a> 1990-2015, Python Software Foundation.
    <br />
    The Python Software Foundation is a non-profit corporation.
    <a href="https://www.python.org/psf/donations/">Please donate.</a>
    <br />
    Last updated on Feb 26, 2015.
    <a href="../bugs.html">Found a bug</a>?
    <br />
    Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.2.3.
    </div>

  </body>
</html>